home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 July / Macworld (1999-07).dmg / Serious Software / OpenWorld demo 2.0 / Development / Utils / Debug / DebugWindow Docs < prev   
Text File  |  1999-04-16  |  9KB  |  231 lines
  1. 
  2.                                                        DebugWindow
  3.  
  4.                                                     by Keith Ledbetter
  5.  
  6.                                      This program may be freely distributed.
  7.  
  8. ••••
  9. Note: DebugWindow requires System 7
  10.  
  11.          Please see the bottom of this document for the latest changes.
  12. ••••
  13.  
  14.  
  15.    DebugWindow is a utility that mimics the Windows 3.x program of the same name.
  16. It allows you to easily print out display strings during the development stages of
  17. your program without any of the headaches normally associated with built-in
  18. "standard I/O" functions.   
  19.  
  20.  
  21.  
  22.  
  23.     DebugWindow's features:
  24.  
  25.  
  26.   •  full "printf()" functionality for C programmers without any added coding on
  27.       your part
  28.  
  29.   •  will remember its location and size on the screen across sessions
  30.  
  31.   •  no more hassles of trying to incorporate Think C's "stdio" window
  32.       in with your pure Toolbox code
  33.  
  34.   •  allows you to save any information that you've printed into its window to a
  35.       TeachText document 
  36.  
  37.   •  callable from either Think C or Hypercard
  38.  
  39.  
  40.  
  41. How does DebugWindow work?
  42. ---------------------------
  43.  
  44.  
  45.   DebugWindow is made up of 2 pieces.   The first is the stand-alone program that sits quietly in the background waiting for an Apple Event to come along for it.   The second piece is either (a) a very small ".lib" file that you include in your Think C (5.x or 6.x)
  46. project or (b) a code resource that you copy into your Hypercard stack with ResEdit.   These pieces contain the "Debug()" function that you call whenever you want to display a string to the DebugWindow.   The "DebugWindow.Lib" file is totally self-contained;  all you need to do to add the functionality to your C program is:
  47.  
  48.     •  Add the "DebugWindow.Lib" file to your Think C project
  49.  
  50.     •  #include "Debug.h" in each of your source files that needs it.
  51.  
  52.     •  if you're not already using one of the ANSI libraries in your
  53.         project, you'll need to add the ANSI-Small library.
  54.  
  55.     •  make sure that the "High Level Events" flag is checked in your
  56.         "Set Project Type / Size" resource.
  57.  
  58.  
  59. or to your Hypercard stack:
  60.  
  61.     •   use ResCopy or ResEdit to copy the code resource "xDebug" into your
  62.          Hypercard stack.
  63.  
  64.  
  65.  
  66. That's it!   Now you can place Debug (or xDebug) statements throughout your C or Hypercard program whenever you feel the need.   For example:
  67.  
  68.  
  69. void MyFunction (short xPos, short yPos)
  70. {
  71.     Debug ( "Doing MyFunction() routine: position is %d,%d\n", xPos, yPos );
  72.     ....    
  73.     if ( yPos < 0 )
  74.         Debug ( "Ack!  Invalid yPos passed by calling function! (%d)\n", yPos );
  75.     .....
  76.     ....
  77. }
  78.  
  79.  
  80. or....
  81.  
  82.  
  83. void GetDataFromHost ()
  84. {
  85.     ....do the DAL stuff....
  86.  
  87.     Debug ( "This data was received from the host:\n" );
  88.     for ( x = 0; x < totalLinesReceived; ++x )
  89.         Debug ( "Host line [%2d]: %-20s %s\n", x, tableName[x], tableVal [x]);
  90.     ....
  91. }
  92.  
  93.  
  94.  
  95. DebugWindow Preferences
  96. ------------------------
  97.  
  98.  
  99.     If the "Automatically add a Carriage Return" box is checked, DebugWindow will
  100. tack a carriage return on the end of any incoming text automatically.   This means
  101. that you don't have to keep remembering to put a "\r" or "\n" on the end of all of
  102. your Debug() strings.
  103.  
  104.  
  105.     If the "Remember Last Position" box is checked, DebugWindow will remember
  106. its window placement and size across executions of the program.
  107.  
  108.  
  109.  
  110. In Conclusion
  111. ------------
  112.  
  113.     If you have any enhancement ideas or questions about DebugWindow (especially if
  114. you find any problems), you can contact me electronically through any of the ID's
  115. listed in the program's "About Box".
  116.  
  117.  
  118. Enjoy!
  119.  
  120.     Keith Ledbetter
  121.       
  122.  
  123.  
  124. Revision History
  125.  
  126.  
  127.   v1.0    • Initial release to a very limited audience.
  128.  
  129.   v1.1    • The "sending program" (that's you) now waits for a reply
  130.                       from DebugWindow; this means that on large streams of
  131.                 Debug() calls, the strings will be immediately displayed
  132.                 in the debug window instead of getting "batched" up.
  133.  
  134.             • DebugWindow will now clear out the display window
  135.                automatically when the buffer is about to fill up.
  136.  
  137.             •    Wrote an XCMD so that Hypercard developers can send
  138.                 messages to DebugWindow.   Simply copy the "xDebug"
  139.                 code resource into your Hypercard stack, and invoke it
  140.                 like this:
  141.  
  142.                                xDebug "This string goes to the DebugWindow" & return
  143.  
  144.   v1.2    •  Internal testing and changes.
  145.  
  146.   v1.3    •  First general public release.
  147.  
  148.   v1.4    •  Added two "tilde lead-in" commands to DebugWindow:
  149.  
  150.                               ~c tells DebugWindow to clear its screen
  151.                         ~t tells DebugWindow to display a timestamp
  152.  
  153.                  These are now implemented in DebugWindow.Lib as 
  154.                  ClearDebugWindow() and DebugTimestamp().  Those of
  155.                  you using Hypercard can simply pass the strings to
  156.                  xDebug as in:   xDebug "~c"
  157.  
  158.             • I've received so many requests for "special" versions of
  159.                DebugWindow.Lib (ie: Pascal, A4, PowerPC, MacApp..) that
  160.                I have decided to include the source code to DebugWindow.Lib
  161.               with this release.   You should find everything you need to know
  162.               in the enclosed Debug.c to implement DebugWindow in whatever
  163.               environment you see fit (you'll need at least some knowledge of
  164.               Apple Events).   Of course, if you have any questions at all, feel
  165.               free to drop me an Email.
  166.  
  167.   v1.5    •  Changed DebugWindow so that it can now display lines up to 512
  168.                  bytes long.
  169.  
  170.              •  Cleaned up the horizontal scroll routine.
  171.  
  172.   v1.6 through v1.9 version numbers were skipped.
  173.  
  174.   v2.0    •  Added a new function called DebugHexDump that will do a hex
  175.                  dump of the buffer specified to the DebugWindow.  The format
  176.                  of the call is as follows:
  177.  
  178.                      DebugHexDump (char *bufferToDump, short lengthToDump);
  179.  
  180.                  Note: not supported under HyperCard.
  181.  
  182.              •  Added the ability to Print the contents of the DebugWindow.  It
  183.                  just didn't seem right to add a nice feature like Hex Dumping and
  184.                  then not have a way to print it out and scribble all over it...
  185.  
  186.              •   You can now use the PageUp/PageDown/Home/End/Arrow keys
  187.                   to scroll through DebugWindow's display.
  188.  
  189.              •  Changed DebugWindow.Lib (source is still included) to allow caching
  190.                  of displays to the window.  If you've done a lot of Debug calls 
  191.                    before, you know that they can sometimes be painstakingly slow.
  192.                  This has been remedied by the addition of two new calls:
  193.  
  194.                              BeginDebug();
  195.                              EndDebug();
  196.  
  197.                   Simply bracket any intense Debug() blocks with BeginDebug() and
  198.                   EndDebug() calls, and you'll see that the response is now almost
  199.                   immediate.   Here's a small example:
  200.  
  201.                                 BeginDebug();
  202.                                 for (x = 0; x < 100; ++x)
  203.                                      Debug ("Loop %d .. how's this for performance?\r", x);
  204.                                 EndDebug();
  205.  
  206.                   Note that you MUST include a matching EndDebug() for every
  207.                   BeginDebug() call!   Also note that this is ONLY available for
  208.                   you C programmers out there; HyperCard programmers do not
  209.                   have access to these calls.
  210.  
  211.                   Note2:  there is no need to bracket DebugHexDump() calls with
  212.                               BeginDebug() and EndDebug() calls, since all of the hex
  213.                               dump processing is internal to DebugWindow.
  214.  
  215.              •  With the BeginDebug and EndDebug additions, the ability to specify
  216.                  that you want DebugWindow to "always append a LineFeed" to your
  217.                  strings no longer made sense.   It has been removed from the
  218.                  Preferences dialog, so make sure that you always tack a "\r" on the
  219.                  end of your Debug display messages.
  220.  
  221.              •  Added a couple of options to the Preferences dialog for controlling
  222.                  the look of Hex Dumps.
  223.  
  224.              •  Changed the calling interface for the DebugTimeStamp and 
  225.                  ClearDebugWindow calls.   Don't do these within a BeginDebug() and
  226.                  EndDebug() envelope, since they can't be cached (it will work fine,
  227.                  but the Timestamp will be printed BEFORE the cache is flushed).
  228.  
  229.              •  Because of the change above, I have included two new HyperCard
  230.                  XCMD's named "xDebugTimeStamp" and "xClearDebugWindow".
  231.